Construcción de la consulta — contrato de extracción hospitalaria

Esta página documenta la consulta: la extracción que el hospital de origen (CSdM — Consorci Sanitari del Maresme) ejecuta sobre su data warehouse clínico y que produce el fichero JSON de entrada del ETL. Describe qué pacientes nos envían y cómo se construye cada variable.

Versión canónica

El documento canónico (en inglés, con las referencias regulatorias completas) vive en el repositorio del ETL: SOURCE_QUERY.md. Ante cualquier discrepancia, ese documento gana. El detalle de las transformaciones que el ETL aplica después está en VARIABLE_CONSTRUCTION.md.

La consulta genera un fichero JSON por extracción (un objeto por paciente, esquema v0.5.0, nombres de campo en catalán), con el histórico completo del paciente dentro de la ventana de exportación. Convención de nombre: YYYYMMDD_pacients_<estudio>_<inicio>_<fin>.json — el prefijo YYYYMMDD es la fecha de generación de la exportación y la referencia de edad de edat.

Qué pacientes nos envían

Criterio	Regla de la consulta	Barrera defensiva del ETL
Edad	Solo pacientes mayores de 64 años (edat mayor que 64, es decir, 65 o más) a la fecha de exportación	El ETL re-aplica age_limit = 65; edad ausente o implausible (menor que 0, mayor que 130) → paciente excluido, nunca corregido en silencio
Unidad asistencial	Pacientes con al menos un episodio en hospitalización (HOSPITALITZACIO), urgencias (URGENCIES) o unidades intermedias (INTERMEDIA)	Clasificación por episodio: otras unidades (RESIDENCIA, U.C.S.I) permanecen en el registro pero no aportan contadores ni datos clínicos
Ventana temporal	Episodios y valoraciones dentro de [db_date_start, db_date_end]	Ventana registrada por extracción en config.py
Identificadores	No se exporta ningún identificador directo (sin nhc, nombre, CIP/DNI)	PiiGuard escanea cada entrada y bloquea la ejecución si aparecen

Cómo se suman los días de estada

El ETL deriva los días de estada de las fechas de cada episodio — nunca se fía de un total pre-sumado por el origen:

1. Por episodio: dias = max(0, dataAlta - dataIngres), en días enteros.
2. stayDays del paciente = suma solo de los episodios de ingreso: HOSPITALITZACIO + INTERMEDIA (la unidad intermedia cuenta como hospitalización completa).
3. Los episodios de URGENCIES incrementan emergencyAdmissions pero suman 0 días de estada.
4. Las unidades excluidas (RESIDENCIA, U.C.S.I) no aportan nada.
5. stayDaysPost = la misma suma restringida a episodios posteriores a la fecha de patología (utilización post-diagnóstico).

Las exportaciones antiguas (v0.4) traían un diesEstadaTotal a nivel de paciente; la tubería actual lo recalcula a partir de las fechas — las fechas del episodio son la única fuente de verdad.

Los ATC: un registro por cada prescripción

La consulta emite exactamente un registro por cada medicamento recetado en cada episodio:

{ "codi": "B01AB", "dataInici": "2022-01-10 00:00:00.0", "dataFi": "2022-01-12 00:00:00.0" }

• codi — código ATC del fármaco recetado.
• dataInici / dataFi — vigencia de la prescripción; si falta dataFi, el tratamiento seguía activo en el momento de la exportación.
• El registro va anidado en el episodio donde se recetó; solo aportan ATCs los episodios cuyo tipus está en contributing_tipus.

El registro por prescripción es la unidad de entrada; la unidad de salida del ETL es una fila por día activo (rango inclusivo [dataInici, dataFi], con tope en db_date_end). No confundir ambas al comparar recuentos con el sistema de origen.

Todas las escalas

Contrato común: cada escala es una lista con una entrada por valoración realizada, fechada por dataValoracio, con un campo por ítem puntuado por el clínico. El total del origen (resultat / total) puede venir, pero el ETL siempre lo recalcula a partir de los ítems y valida cada ítem contra su conjunto canónico publicado (un ítem inválido descarta la valoración entera, contándola en la auditoría).

Escala (campo de origen)	Ítems que envía la consulta	Total
barthel	usoWc, bany, alimentacio, vestirse, controlAnal, transferencia, caminar, higiene, controlVesical, escales (+ total opcional)	0–100
mna (MNA-SF)	anorexia, perduaPes, mobilitat, malaltiaAgudaEstresPsicologic, problemesNeuropsicologics, imc (ítem IMC puntuado, 0–3; opcional — el MNA-SF admite sustitución IMC/pantorrilla) — resultat es el total del origen, no un ítem	0–14
mna_completa (MNA completo)	los ítems del MNA-SF + independent, multiMedicacio, ulceresLesionsCutaneas, menjarsComplets, consumProteic, consumFruita, gotsLiquids, formaAlimentacio, nutricio, estatSalut, cb, cp — cb/cp llegan como circunferencias en cm y el ETL las convierte a su puntuación MNA; resultat es el total del origen	0–30
emina	estatMental, mobilitat, humitat, nutricio, activitat — cada uno 0–3	0–15
canadenca (Escala Neurológica Canadiense)	mentación nivellConsciencia, orientacio, llenguatge + una rama motora: A1 cara, bracProximal, bracDistal, cama o A2 deficitReceptiuCara, deficitReceptiuBracos, deficitReceptiuCames	A1 llega a 10.0 (pierna combinada cama)
mecvv (MECV-V)	dataValoracio, indicadores disfagia, disfagiaConeguda, pacientNoColabora + detalle del test alteracioEficacia, alteracioSeguretat, viscositat, volum	— (categórica; 6 reglas de validación clínica)
vfs (videofluoroscopia)	resultat (legado result) en texto libre (ca/es/en)	— (se canoniza a Sí/No/indeterminado)

Se envían pero no se procesan: braden, morse, tinetti, gdsFast, miniMental, nihss (nuevas en el esquema v0.5.0). Se toleran como campos extra no reconocidos — el validador de ficheros solo comprueba que los campos obligatorios estén presentes, no rechaza extras — y ningún parser las ingiere, así que no aparecen en el dataset de salida.

El resto de variables

• Demografía — edat (años cumplidos a la fecha de exportación), sexe (F/M; otro valor anula el campo, no excluye al paciente), talla (cm; el ETL acepta 30–250) y poblacioResidencia (llega en el JSON de origen pero no se procesa ni aparece en la salida).
• Episodios (ingressos) — una entrada por episodio asistencial: dataIngres, dataAlta, tipus, diagnóstico principal (codiDiagnosticPrincipal) + secundarios (codiDiagnostics), atcs, provesLaboratori.
• Diagnósticos ICD — principal + secundarios por episodio, tal como se codifican al alta (ICD-9 o ICD-10 según la época); el ETL los fecha en el alta y normaliza ICD-9 → ICD-10.
• Laboratorio (provesLaboratori) — un registro por resultado de analito (loinc/codi, name/nom, value/valor, data), anidado por episodio.
• Pesos (pesos) — una entrada por medición: valor, data, imc.

Catálogo de extracciones

Clave	Estado	Ventana de datos	Codificación
MECVV	disponible (producción)	2013-01-01 → 2023-07-07	windows-1252
MECVV_2025	desarrollo (exportación vigente, pendiente de validación de cohorte)	2013-03-07 → 2025-03-07	utf-8
VFS	desarrollo (plantilla)	2015-01-01 → 2025-03-01	utf-8
PRE_INTERVENTION	desarrollo (plantilla)	2021-01-01 → 2022-01-01	utf-8
POST_INTERVENTION_2022	desarrollo (plantilla)	2022-02-01 → 2023-02-01	utf-8
RESPIRATORY	desarrollo (plantilla)	2018-01-01 → 2025-03-01	utf-8
MALNUTRITION_SPECIFIC	desarrollo (plantilla)	2013-03-01 → 2025-05-01	utf-8

Una nueva exportación del hospital = una nueva entrada en CONFIGS (config.py del repositorio del ETL), nunca una edición de la lógica clínica.